Auto merge of #2610 - japaric:install-from-tempdir, r=alexcrichton

cargo-install: prefer building artifacts in the system temporary directory

and each cargo-install instance creates and uses its own build directory. This
allows running several cargo-install instances in parallel.

If we fail to create a temporary directory for whatever reason fallback to
creating and using a target-install directory in the current directory.

closes #2606

---

r? @alexcrichton

Qs:
- Should we preserve the current behavior (`target-install` in `cwd`) as a fallback or remove it and error if we can't create a `TempDir` in `env::temp_dir()`? (we currently error if we can't create `target-install` directory in `cwd`)

- Should I add tests for the issues I raised at #2606? If yes, how can I test `cargo-install` parallelism? Lack of "Blocking waiting for file lock on build directory" in the output of the `cargo` commands? or something else?

add tests for #2606

cargo-install: prefer building artifacts in the system temporary directory

and each cargo-install instance creates and uses its own build directory. This
allows running several cargo-install instances in parallel.

If we fail to create a temporary directory for whatever reason fallback to
creating and using a target-install directory in the current directory.

closes #2606

Auto merge of #2602 - durka:patch-5, r=alexcrichton

fix rerun-if-changed documentation

The documentation corresponded to the initial proposed implementation, which was changed to remove special handling of directories before it was ever merged.

closes #2599
r? @alexcrichton

fix rerun-if-changed documentation

The documentation corresponded to the initial proposed implementation, which was changed to remove special handling of directories before it was ever merged.

Auto merge of #2578 - alexcrichton:test-doc, r=brson

Add `cargo test --doc`

Supports testing only the documentation (like `--lib`, `--bin`, etc).

Auto merge of #2551 - alexcrichton:explain, r=brson

Add support for `cargo --explain`

The error messages in the compiler are being tweaked and will likely drop the
`rustc --explain` part of the error message in favor of `--explain`. In that
case you're expected to basically take whatever tool you're using and pass
`--explain` to it with an error code, so let's add it to Cargo as well!

Add support for `cargo --explain`

The error messages in the compiler are being tweaked and will likely drop the
`rustc --explain` part of the error message in favor of `--explain`. In that
case you're expected to basically take whatever tool you're using and pass
`--explain` to it with an error code, so let's add it to Cargo as well!

Auto merge of #2576 - alexcrichton:silence-warnings-with-q, r=brson

Don't print warnings when -q is passed

Closes #2571

Auto merge of #2579 - alexcrichton:robust-submodule, r=brson

Remove submodule directory before cloning

If the directory is in a corrupt state that caused an existing repository to not
successfully open, then we'll want to blow it away anything that already exists
to ensure we start from a clean slate.

Closes #2567

Auto merge of #2577 - alexcrichton:doc-lib-flags, r=brson

Add `cargo doc --lib/--bin`

Allows documenting a specific target.

Closes #2557

Auto merge of #2560 - alexcrichton:not-all-utf8, r=brson

Don't require all build script output to be utf-8

Build scripts often stream output of native build systems like cmake/make and
those aren't always guaranteed to produce utf-8 output. For example  German
MSVC cmake build has been reported to print non-utf-8 umlauts.

This commit instead only attempts to interpret each line as utf-8 rather than
the entire build script output. All non-utf-8 output is ignored.

Closes #2556

Auto merge of #2501 - ryanq:issue2266, r=alexcrichton

Check local targets before resolving dependencies

A call to `generate_targets(...)` before calling `resolve_dependencies()`
catches invalid target names before fetching the source for the
dependencies.

Closes #2266

Auto merge of #2592 - jethrogb:topic/list-symlinks, r=alexcrichton

Use stat() instead of lstat() in cargo --list

The OS-specific implementation is necessary because according to the docs, [DirEntry::metadata is fast on Windows](https://doc.rust-lang.org/stable/std/fs/struct.DirEntry.html#method.metadata). Note  `is_executable` is used elsewhere so we can't change that directly to accept `DirEntry` instead of `Metadata`.

Fixes #2591

Fix dead code lints on Windows

Style issue

Add test list_command_resolves_symlinks

Tests: fix grammar and extra semicolon

Style issue

Auto merge of #2590 - alexcrichton:dont-warn-about-flags-and-configs, r=brson

Have CLI take preference over config for verbosity

If a CLI option is passed, that trumps any command line configuration, otherwise
just do what we did previously.

Closes #2588

Use stat() instead of lstat() in cargo --list. Fixes #2591

Have CLI take preference over config for verbosity

If a CLI option is passed, that trumps any command line configuration, otherwise
just do what we did previously.

Closes #2588

Auto merge of #2584 - alexcrichton:auth-more, r=brson

Correctly attempt multiple usernames with libgit2

This commit corrects the logic for attempting multiple usernames with libgit2.
There is a restriction that for each authentication seession you can only
authenticate with one ssh username, but we were attempting multiple as part of
the same sesssion. Instead restart authentication whenever we try a new username.

Closes #2399

Correctly attempt multiple usernames with libgit2

This commit corrects the logic for attempting multiple usernames with libgit2.
There is a restriction that for each authentication seession you can only
authenticate with one ssh username, but we were attempting multiple as part of
the same sesssion. Instead restart authentication whenever we try a new username.

Closes #2399

Merge pull request #2587 from birkenfeld/docmenu

Doc dropdown menu: name "Cargo.toml" explicitly

Doc dropdown menu: name "Cargo.toml" explicitly

Add `cargo test --doc`

Supports testing only the documentation (like `--lib`, `--bin`, etc).

Add `cargo doc --lib/--bin`

Allows documenting a specific target.

Closes #2557

Remove submodule directory before cloning

If the directory is in a corrupt state that caused an existing repository to not
successfully open, then we'll want to blow it away anything that already exists
to ensure we start from a clean slate.

Closes #2567

Auto merge of #2575 - alexcrichton:bump, r=alexcrichton

Bump to 0.11.0

Don't print warnings when -q is passed

Closes #2571

Bump to 0.11.0

Auto merge of #2574 - alexcrichton:crates-io-bump, r=alexcrichton

Bump the crates-io crate to 0.2

Bump the crates-io crate to 0.2

Auto merge of #2562 - smaximov:doc-add-env-vars, r=alexcrichton

Document env vars introduced in PR #2523 to the docs

Document environment variables introduced in #2523 (`CARGO_PKG_NAME`, `CARGO_PKG_DESCRIPTION`, `CARGO_PKG_HOMEPAGE`).

Add reference to env vars introduced in PR #2523 to the docs

Auto merge of #2561 - alexcrichton:update-tar, r=alexcrichton

Update dependency on tar

Includes a fix for alexcrichton/tar-rs#61

Update dependency on tar

Includes a fix for alexcrichton/tar-rs#61

Don't require all build script output to be utf-8

Build scripts often stream output of native build systems like cmake/make and
those aren't always guaranteed to produce utf-8 output. For example  German
MSVC cmake build has been reported to print non-utf-8 umlauts.

This commit instead only attempts to interpret each line as utf-8 rather than
the entire build script output. All non-utf-8 output is ignored.

Closes #2556

Auto merge of #2554 - alexcrichton:robust-test, r=alexcrichton

Make a test a bit more robust to the environment

Don't filter out PATH as `rustc` may be in that directory (e.g. when using
rustup) and otherwise just have a longer subcommand.

Closes #2553

Make a test a bit more robust to the environment

Don't filter out PATH as `rustc` may be in that directory (e.g. when using
rustup) and otherwise just have a longer subcommand.

Closes #2553

Auto merge of #2465 - TheNeikos:add-version_env, r=alexcrichton

Add a new CARGO_PKG_AUTHORS environment variable

This will allow crates to use the CARGO_PKG_AUTHORS env variable to get a comma
seperated list of the authors declared in the manifest.

Closes #2441

Add a new CARGO_PKG_AUTHORS environment variable

This will allow crates to use the CARGO_PKG_AUTHORS env variable to get a colon
seperated list of the authors declared in the manifest.

Closes #2441

Merge remote-tracking branch 'origin/master' into issue2266

Only validate targets if the spec option is empty

Auto merge of #2385 - alexcrichton:top-level-overrides, r=wycats

Implement top-level overrides

This commit is an implementation of top-level overrides to be encoded into the
manifest itself directly. This style of override is distinct from the existing
`paths` support in `.cargo/config` in two important ways:

* Top level overrides are intended to be checked in and shared amongst all
  developers of a project.
* Top level overrides are reflected in `Cargo.lock`.

The second point is crucially important here as it will ensure that an override
on one machine behaves the same as an override on another machine. This solves
many long-standing problems with `paths`-based overrides which suffer from some
level of nondeterminism as they're not encoded.

From a syntactical point of view, an override looks like:

```toml
[replace]
"libc:0.2.0" = { git = 'https://github.com/my-username/libc';, branch = '0.2-fork' }
```

This declaration indicates that whenever resolution would otherwise encounter
the `libc` package version 0.2.0 from crates.io, it should instead replace it
with the custom git dependency on a specific branch.

The key "libc:0.2.0" here is actually a package id specification which will
allow selecting various components of a graph. For example the same named
package coming from two distinct locations can be selected against, as well as
multiple versions of one crate in a dependency graph. The replacement dependency
has the same syntax as the `[dependencies]` section of Cargo.toml.

One of the major uses of this syntax will be, for example, using a temporary
fork of a crate while the changes are pushed upstream to the original repo. This
will avoid the need to change the intermediate projects immediately, and over
time once fixes have landed upstream the `[replace]` section in a `Cargo.toml`
can be removed.

There are also two crucial restrictions on overrides.

* A crate with the name `foo` can only get overridden with packages also of
  the name `foo`.
* A crate can only get overridden with a crate of the exact same version.

A consequence of these restrictions is that crates.io cannot be used to replace
anything from crates.io. There's only one version of something on crates.io, so
there's nothing else to replace it with (name/version are a unique key).

Closes #942

Auto merge of #2547 - alexcrichton:more-locking, r=brson

Add file locks in a few more locations

One was discovered by making `target_dir` return a `Filesystem`, the other was discovered by failing tests on the nightly OSX bots.

Protect against concurrent access to Cargo.lock

CI tests seen to be spurious failing on OSX due to this, I believe it's because
one process is concurrently writing out Cargo.lock while the other is trying to
read it in, so one of them gets a corrupt version.

This would ideally be fixed from `pkg.root()` returning a `Filesystem`, but that
was unfortunately such an invasive change that it seemed untenable. Additionally
we generally don't write files into the source tree, so if this is the only
instance it's perhaps not so bad trying to be robust in to the future.

Change `Config::target_dir` to return Filesystem

This is a shared directory among multiple Cargo processes so access to it needs
to be properly synchronized. This commit changes the API of `Config::target_dir`
and then propagates the changes outward as necessary.

One fallout of this change is now we allow release/debug builds to proceed in
parallel.

Auto merge of #2541 - alexcrichton:aarch64, r=alexcrichton

Download the aarch64 standard library on the bots

Download the aarch64 standard library on the bots

Auto merge of #2534 - alexcrichton:lock-with-git-repos, r=brson

Replace existing sources before updating

Currently sources may acquire file locks to ensure that they're not tampered
with while they're in use. We may load two sources to the same location,
however, in the case of git repositories which need to be updated. Cargo will
first load a locked version of the source and then may load an unlocked version,
and these two loads currently deadlock.

This commit tweaks the logic when updating a source to only update it after the
previous source has been replaced.

Closes #2533

Auto merge of #2538 - alexcrichton:aarch64, r=alexcrichton

Prepare for aarch64 nightlies and CI

Prepare for aarch64 nightlies and CI

Auto merge of #2505 - srinivasreddy:improve_msg, r=alexcrichton

Create `Cargo.lock` if it does not exist.

remote unnecessary expression

Auto merge of #2491 - JIghtuse:master, r=alexcrichton

Reject manifest with duplicate dependencies in different targets

Closes #2023

Generate the lock file when there is no lock file

Replace existing sources before updating

Currently sources may acquire file locks to ensure that they're not tampered
with while they're in use. We may load two sources to the same location,
however, in the case of git repositories which need to be updated. Cargo will
first load a locked version of the source and then may load an unlocked version,
and these two loads currently deadlock.

This commit tweaks the logic when updating a source to only update it after the
previous source has been replaced.

Closes #2533

Auto merge of #2532 - japaric:musl, r=alexcrichton

install-deps.py: add x86_64-unknown-linux-musl target

This lets me build a statically linked cargo on our linux-cross Docker image with the following
commands:

$ apt-get install musl-tools # for musl-gcc, which is needed to build openssl
$ ./.travis.install.deps.sh
$ ./configure --local-rust-root=$(pwd)/rustc --enable-nightly --target=x86_64-unknown-linux-musl
$ make
$ file target/x86_64-unknown-linux-musl/release/cargo
cargo: ELF 64-bit LSB executable, x86-64, version 1 (GNU/Linux), statically linked (..)

---

r? @alexcrichton -- If we want start building cargo for this target on the bots, we'll have to modify the linux-cross Dockerfile to install musl-tools.
cc @eddyb

Auto merge of #2531 - alexcrichton:fix-stdin, r=alexcrichton

Update Rust to pick up rust-lang/rust#32257

Closes #2530

Update Rust to pick up rust-lang/rust#32257

Closes #2530

install-deps.py: add x86_64-unknown-linux-musl target

This lets me build a statically linked cargo on our linux-cross Docker image with the following
commands:

$ apt-get install musl-tools # for musl-gcc, which is needed to build openssl
$ ./.travis.install.deps.sh
$ ./configure --local-rust-root=$(pwd)/rustc --enable-nightly --target=x86_64-unknown-linux-musl
$ make
$ file target/x86_64-unknown-linux-musl/release/cargo
cargo: ELF 64-bit LSB executable, x86-64, version 1 (GNU/Linux), statically linked (..)

Auto merge of #2523 - srinivasreddy:issue-2504, r=alexcrichton

expose cargo package name as CARGO_PKG_NAME

implemented cargo package name as CARGO_PKG_NAME; And package description and home page are exposed as  CARGO_PKG_DESCRIPTION and CARGO_PKG_HOMEPAGE respectively. And add a test case - for CARGO_PKG_NAME, CARGO_PKR_DESCRIPTION, CARGO_HOMEPAGE.

Implement top-level overrides

This commit is an implementation of top-level overrides to be encoded into the
manifest itself directly. This style of override is distinct from the existing
`paths` support in `.cargo/config` in two important ways:

* Top level overrides are intended to be checked in and shared amongst all
  developers of a project.
* Top level overrides are reflected in `Cargo.lock`.

The second point is crucially important here as it will ensure that an override
on one machine behaves the same as an override on another machine. This solves
many long-standing problems with `paths`-based overrides which suffer from some
level of nondeterminism as they're not encoded.

From a syntactical point of view, an override looks like:

```toml
[replace]
"libc:0.2.0" = { git = 'https://github.com/my-username/libc', branch = '0.2-fork' }
```

This declaration indicates that whenever resolution would otherwise encounter
the `libc` package version 0.2.0 from crates.io, it should instead replace it
with the custom git dependency on a specific branch.

The key "libc:0.2.0" here is actually a package id specification which will
allow selecting various components of a graph. For example the same named
package coming from two distinct locations can be selected against, as well as
multiple versions of one crate in a dependency graph. The replacement dependency
has the same syntax as the `[dependencies]` section of Cargo.toml.

One of the major uses of this syntax will be, for example, using a temporary
fork of a crate while the changes are pushed upstream to the original repo. This
will avoid the need to change the intermediate projects immediately, and over
time once fixes have landed upstream the `[replace]` section in a `Cargo.toml`
can be removed.

There are also two crucial restrictions on overrides.

* A crate with the name `foo` can only get overridden with packages also of
  the name `foo`.
* A crate can only get overridden with a crate of the exact same version.

A consequence of these restrictions is that crates.io cannot be used to replace
anything from crates.io. There's only one version of something on crates.io, so
there's nothing else to replace it with (name/version are a unique key).

Closes #942

Auto merge of #2519 - alexcrichton:update-curl, r=alexcrichton

Update curl-sys

Picks up a fix to hopefully and correctly configure OpenSSL to be enabled in
cross-compiled situations where OpenSSL comes from a different location
(currently specified by the `OPENSSL_ROOT_DIR` environment variable that libssh2
also reads).

Update curl-sys

Picks up a fix to hopefully and correctly configure OpenSSL to be enabled in
cross-compiled situations where OpenSSL comes from a different location
(currently specified by the `OPENSSL_ROOT_DIR` environment variable that libssh2
also reads).

Auto merge of #2513 - alexcrichton:xcompile, r=alexcrichton

Fix nightly dist builds

* When downloading rustc, also download a number of cross-std libraries so we
  can cross compile with that compiler.
* Only build OpenSSL on some --enable-nightly builds, not all. For example
  Windows and OSX don't want to link statically to OpenSSL.

Fix nightly dist builds

* When downloading rustc, also download a number of cross-std libraries so we
  can cross compile with that compiler.
* Only build OpenSSL on some --enable-nightly builds, not all. For example
  Windows and OSX don't want to link statically to OpenSSL.

Auto merge of #2510 - alexcrichton:xcompile, r=brson

Prepare for ARM/FreeBSD/NetBSD nightlies

This commit beefs up Cargo's makefiles to support nightly builds of Cargo for
multiple platforms. This primarily involves vendoring the logic of how to build
OpenSSL for statically linking against Cargo into the Makefiles directly. We'll
have to update the version of OpenSSL as releases are made, but we essentially
already do that with the normal docker container.

The Linux nightlies will still run in the normal dist docker container (a really
old CentOS build) and builds for new platforms will happen in the standard
linux-cross container we use for other cross builds. The nightly versions of
these will produce Cargo tarballs for a whole bunch of platforms to get
uploaded.

This has been tested in the `alexcrichton/rust-slave-linux-cross:2016-03-17b`
docker container for the 3 ARM targets and FreeBSD target. NetBSD will come once
rust-lang/rust#32407 lands.

Prepare for ARM/FreeBSD/NetBSD nightlies

This commit beefs up Cargo's makefiles to support nightly builds of Cargo for
multiple platforms. This primarily involves vendoring the logic of how to build
OpenSSL for statically linking against Cargo into the Makefiles directly. We'll
have to update the version of OpenSSL as releases are made, but we essentially
already do that with the normal docker container.

The Linux nightlies will still run in the normal dist docker container (a really
old CentOS build) and builds for new platforms will happen in the standard
linux-cross container we use for other cross builds. The nightly versions of
these will produce Cargo tarballs for a whole bunch of platforms to get
uploaded.

This has been tested in the `alexcrichton/rust-slave-linux-cross:2016-03-17b`
docker container for the 3 ARM targets and FreeBSD target. NetBSD will come once
rust-lang/rust#32407 lands.

Auto merge of #2440 - ThinTim:master, r=alexcrichton

Prevent the use of "test" as a crate name

Fixes #2432

?r @alexcrichton

Prevent the use of "test" as a crate name. Fixes #2432.

Reject manifest with duplicate dependencies in different targets

Closes #2023

Auto merge of #2502 - IvanUkhov:doc, r=alexcrichton

doc: make the pages’ titles consistent

The titles of some of the pages end with “Cargo Documentation” (_e.g._, [Frequently Asked Questions](http://doc.crates.io/faq.html)) whereas the titles of some other pages do not (_e.g._, [Environment Variables](http://doc.crates.io/environment-variables.html)), which is a bit inconsistent. Perhaps one should either add that ending to all the titles or eliminate it from all of them. This pull request does the latter, which can be changed if needed. I personally think that such long titles are reasonable for the `title` HTML tag but a bit too verbose when displayed on the page.

doc: make the pages’ titles consistent

Check local targets before resolving dependencies

A call to generate_targets() before calling resolve_dependencies()
catches invalid target names before fetching the source for the
dependencies.

Auto merge of #2499 - IvanUkhov:typography, r=alexcrichton

doc/manifest: turn the list in Rules into an unordered one

Please see the comments in #2493.

doc/manifest: turn the list in Rules into an unordered one

Auto merge of #2496 - alexcrichton:fix-concurrent, r=alexcrichton

Relax an assertion in the concurrent tests

The output may also have information about blocking, we just want the successful
part.

Auto merge of #2482 - ryanq:issue2266, r=alexcrichton

Suggest the best matching target for cargo run

Targets passed to cargo compile are validated against the package. If
the target exists, it is compiled. If not, cargo will bail and offer a
suggested target name if there is a close match.

The tests create and build/run binaries and examples using filenames
that are close (or not so close) to the target names to verify that
close matching names are suggested to the user.

Sample output attached.
<img width="838" alt="screen shot 2016-03-14 at 12 32 59 pm" src="https://cloud.githubusercontent.com/assets/124247/13754913/28490e42-e9ef-11e5-9617-8d3c01106527.png">

Closes #2266

Relax an assertion in the concurrent tests

The output may also have information about blocking, we just want the successful
part.

Auto merge of #2493 - IvanUkhov:typography, r=alexcrichton

doc/manifest: polish typography

The pull request makes a number of stylistic adjustments to The Manifest Format page. There are two commits. The first is a preliminary reflowing of paragraphs, and the second bears the actual changes. If any of the changes seems dubious, please let me know; I’ll try to motivate (and revert if needed).

Fixing line length error in make test

Bring in changes from master

Move suggestion logic into generate_targets()

doc/manifest: polish typography

doc/manifest: respect 80 characters

Auto merge of #2467 - tshepang:rustfmt, r=alexcrichton

run rustfmt on core/source.rs

Auto merge of #2480 - alexcrichton:ui, r=alexcrichton

Tweak UI for warnings and errors

Right now Cargo prints out errors justified like all other status messages, but
this can look odd without coloration:

```
   error some error message
```

Instead, this commit changes both warnings and errors to use the same style of:

```
error: some error message
warning: some warning message
```

Additionally, warnings now only print out "warning" in yellow instead of the
entire message (like errors do)

Tweak UI for warnings and errors

Right now Cargo prints out errors justified like all other status messages, but
this can look odd without coloration:

```
   error some error message
```

Instead, this commit changes both warnings and errors to use the same style of:

```
error: some error message
warning: some warning message
```

Additionally, warnings now only print out "warning" in yellow instead of the
entire message (like errors do)

run rustfmt on core/source.rs

Includes manual adjustments

Auto merge of #2486 - alexcrichton:flock, r=brson

Fix running Cargo concurrently

Cargo has historically had no protections against running it concurrently. This
is pretty unfortunate, however, as it essentially just means that you can only
run one instance of Cargo at a time **globally on a system**.

An "easy solution" to this would be the use of file locks, except they need to
be applied judiciously. It'd be a pretty bad experience to just lock the entire
system globally for Cargo (although it would work), but otherwise Cargo must be
principled how it accesses the filesystem to ensure that locks are properly
held. This commit intends to solve all of these problems.

A new utility module is added to cargo, `util::flock`, which contains two types:

* `FileLock` - a locked version of a `File`. This RAII guard will unlock the
  lock on `Drop` and I/O can be performed through this object. The actual
  underlying `Path` can be read from this object as well.
* `Filesystem` - an unlocked representation of a `Path`. There is no "safe"
  method to access the underlying path without locking a file on the filesystem
  first.

Built on the [fs2] library, these locks use the `flock` system call on Unix and
`LockFileEx` on Windows. Although file locking on Unix is [documented as not so
great][unix-bad], but largely only because of NFS, these are just advisory, and
there's no byte-range locking. These issues don't necessarily plague Cargo,
however, so we should try to leverage them. On both Windows and Unix the file
locks are released when the underlying OS handle is closed, which means that
if the process dies the locks are released.

Cargo has a number of global resources which it now needs to lock, and the
strategy is done in a fairly straightforward way:

* Each registry's index contains one lock (a dotfile in the index). Updating the
  index requires a read/write lock while reading the index requires a shared
  lock. This should allow each process to ensure a registry update happens while
  not blocking out others for an unnecessarily long time. Additionally any
  number of processes can read the index.
* When downloading crates, each downloaded crate is individually locked. A lock
  for the downloaded crate implies a lock on the output directory as well.
  Because downloaded crates are immutable, once the downloaded directory exists
  the lock is no longer needed as it won't be modified, so it can be released.
  This granularity of locking allows multiple Cargo instances to download
  dependencies in parallel.
* Git repositories have separate locks for the database and for the project
  checkout. The datbase and checkout are locked for read/write access when an
  update is performed, and the lock of the checkout is held for the entire
  lifetime of the git source. This is done to ensure that any other Cargo
  processes must wait while we use the git repository. Unfortunately there's
  just not that much parallelism here.
* Binaries managed by `cargo install` are locked by the local metadata file that
  Cargo manages. This is relatively straightforward.
* The actual artifact output directory is just globally locked for the entire
  build. It's hypothesized that running Cargo concurrently in *one directory* is
  less of a feature needed rather than running multiple instances of Cargo
  globally (for now at least). It would be possible to have finer grained
  locking here, but that can likely be deferred to a future PR.

So with all of this infrastructure in place, Cargo is now ready to grab some
locks and ensure that you can call it concurrently anywhere at any time and
everything always works out as one might expect.

One interesting question, however, is what does Cargo do on contention? On one
hand Cargo could immediately abort, but this would lead to a pretty poor UI as
any Cargo process on the system could kick out any other. Instead this PR takes
a more nuanced approach.

* First, all locks are attempted to be acquired (a "try lock"). If this
  succeeds, we're done.
* Next, Cargo prints a message to the console that it's going to block waiting
  for a lock. This is done because it's indeterminate how long Cargo will wait
  for the lock to become available, and most long-lasting operations in Cargo
  have a message printed for them.
* Finally, a blocking acquisition of the lock is issued and we wait for it to
  become available.

So all in all this should help Cargo fix any future concurrency bugs with file
locking in a principled fashion while also allowing concurrent Cargo processes
to proceed reasonably across the system.

[fs2]: https://github.com/danburkert/fs2-rs
[unix-bad]: http://0pointer.de/blog/projects/locking.html

Closes #354

Fix running Cargo concurrently

Cargo has historically had no protections against running it concurrently. This
is pretty unfortunate, however, as it essentially just means that you can only
run one instance of Cargo at a time **globally on a system**.

An "easy solution" to this would be the use of file locks, except they need to
be applied judiciously. It'd be a pretty bad experience to just lock the entire
system globally for Cargo (although it would work), but otherwise Cargo must be
principled how it accesses the filesystem to ensure that locks are properly
held. This commit intends to solve all of these problems.

A new utility module is added to cargo, `util::flock`, which contains two types:

* `FileLock` - a locked version of a `File`. This RAII guard will unlock the
  lock on `Drop` and I/O can be performed through this object. The actual
  underlying `Path` can be read from this object as well.
* `Filesystem` - an unlocked representation of a `Path`. There is no "safe"
  method to access the underlying path without locking a file on the filesystem
  first.

Built on the [fs2] library, these locks use the `flock` system call on Unix and
`LockFileEx` on Windows. Although file locking on Unix is [documented as not so
great][unix-bad], but largely only because of NFS, these are just advisory, and
there's no byte-range locking. These issues don't necessarily plague Cargo,
however, so we should try to leverage them. On both Windows and Unix the file
locks are released when the underlying OS handle is closed, which means that
if the process dies the locks are released.

Cargo has a number of global resources which it now needs to lock, and the
strategy is done in a fairly straightforward way:

* Each registry's index contains one lock (a dotfile in the index). Updating the
  index requires a read/write lock while reading the index requires a shared
  lock. This should allow each process to ensure a registry update happens while
  not blocking out others for an unnecessarily long time. Additionally any
  number of processes can read the index.
* When downloading crates, each downloaded crate is individually locked. A lock
  for the downloaded crate implies a lock on the output directory as well.
  Because downloaded crates are immutable, once the downloaded directory exists
  the lock is no longer needed as it won't be modified, so it can be released.
  This granularity of locking allows multiple Cargo instances to download
  dependencies in parallel.
* Git repositories have separate locks for the database and for the project
  checkout. The datbase and checkout are locked for read/write access when an
  update is performed, and the lock of the checkout is held for the entire
  lifetime of the git source. This is done to ensure that any other Cargo
  processes must wait while we use the git repository. Unfortunately there's
  just not that much parallelism here.
* Binaries managed by `cargo install` are locked by the local metadata file that
  Cargo manages. This is relatively straightforward.
* The actual artifact output directory is just globally locked for the entire
  build. It's hypothesized that running Cargo concurrently in *one directory* is
  less of a feature needed rather than running multiple instances of Cargo
  globally (for now at least). It would be possible to have finer grained
  locking here, but that can likely be deferred to a future PR.

So with all of this infrastructure in place, Cargo is now ready to grab some
locks and ensure that you can call it concurrently anywhere at any time and
everything always works out as one might expect.

One interesting question, however, is what does Cargo do on contention? On one
hand Cargo could immediately abort, but this would lead to a pretty poor UI as
any Cargo process on the system could kick out any other. Instead this PR takes
a more nuanced approach.

* First, all locks are attempted to be acquired (a "try lock"). If this
  succeeds, we're done.
* Next, Cargo prints a message to the console that it's going to block waiting
  for a lock. This is done because it's indeterminate how long Cargo will wait
  for the lock to become available, and most long-lasting operations in Cargo
  have a message printed for them.
* Finally, a blocking acquisition of the lock is issued and we wait for it to
  become available.

So all in all this should help Cargo fix any future concurrency bugs with file
locking in a principled fashion while also allowing concurrent Cargo processes
to proceed reasonably across the system.

[fs2]: https://github.com/danburkert/fs2-rs
[unix-bad]: http://0pointer.de/blog/projects/locking.html

Closes #354

Auto merge of #2490 - alexcrichton:rustflags-docs, r=alexcrichton

Add docs for RUSTFLAGS and build.rustflags

Auto merge of #2484 - alexcrichton:fix-bad-backtrack, r=brson

Fix caching features across backtracking

In the local loop during resolution all variables need to be reset whenever we
backtrack up a frame, but currently the `method` and `features` set are
accidentally not reset whenever we backtrack. Calculate the `method` later and
cache `features` in each frame so we can properly backtrack.

Closes #2472

Add docs for RUSTFLAGS and build.rustflags

Auto merge of #2241 - brson:rustflags, r=alexcrichton

Apply RUSTFLAGS arguments to rustc builds

Cargo will use RUSTFLAGS for building everything that is not a build script
or plugin. It does not apply to these targets because they may be for
a different platform that 'normal' builds.

Closes #2112

Fix caching features across backtracking

In the local loop during resolution all variables need to be reset whenever we
backtrack up a frame, but currently the `method` and `features` set are
accidentally not reset whenever we backtrack. Calculate the `method` later and
cache `features` in each frame so we can properly backtrack.

Closes #2472